<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>LuaXML reference</title>
    <link rel="stylesheet" href="ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>LuaXML</h1>


<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Fields">Fields</a></li>
</ul>


<h2>Modules</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap'">
  <li><strong>LuaXML</strong></li>
</ul>

</div>

<div id="content">

<h1>Module <code>LuaXML</code></h1>
<p>A module that maps between Lua and XML without much ado.</p>
<p>LuaXML provides a set of functions for processing XML data in Lua.
It offers a very simple and natural mapping between the XML format and Lua tables,
which allows one to work with and construct XML data just using Lua&rsquo;s normal
table access and iteration methods (e.g. <code>ipairs()</code>).</p>

<p>Substatements and tag content are represented as array data having numerical
keys (<code>1 .. n</code>), attributes use string keys, and tags the numerical index <code>0</code>.
This representation makes sure that the structure of XML data is preserved
exactly across read/write cycles (i.e. <code>xml.eval(var:str())</code> should equal <code>var</code>
again).</p>

<hr />

<br>To use LuaXML, first import the module - for example like this:


<pre><code>local xml = require("LuaXML")
</code></pre>

<p>LuaXML consists of a Lua file (<code>LuaXML.lua</code>) and a corresponding C module
(<code>LuaXML_lib</code>) &ndash; normally a shared library (<code>.dll</code>/<code>.so</code>), although a static
linking is possible as well. Both parts are imported by this call, provided
that they are found in Lua&rsquo;s package search path.</p>

<p>&nbsp;</p>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#append">append (var, tag)</a></td>
	<td class="summary">appends a new subordinate LuaXML object to an existing one.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#children">children (var, tag, key, value, maxdepth)</a></td>
	<td class="summary">iterate subelements (&ldquo;XML children&rdquo;) as <em>key &ndash; value</em> pairs.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#decode">decode (str)</a></td>
	<td class="summary">converts a string from XML encoding.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#encode">encode (str)</a></td>
	<td class="summary">converts a string to XML encoding.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#eval">eval (xml, mode)</a></td>
	<td class="summary">parses an XML string into a Lua table.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#find">find (var, tag, key, value)</a></td>
	<td class="summary">recursively searches a Lua table for a subelement
matching the provided tag and attribute.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#iterate">iterate (var, cb, tag, key, value, r, max, d)</a></td>
	<td class="summary">iterates a LuaXML object,
invoking a callback function for all matching (sub)elements.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#load">load (filename, mode)</a></td>
	<td class="summary">loads XML data from a file and returns it as table.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#match">match (var, tag, key, value)</a></td>
	<td class="summary">match XML entity against given (optional) criteria.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#new">new (arg, tag)</a></td>
	<td class="summary">creates a LuaXML &ldquo;object&rdquo;, and optionally sets its tag.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#registerCode">registerCode (decoded, encoded)</a></td>
	<td class="summary">registers a custom code for the conversion between non-standard characters
and XML character entities.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#save">save (var, filename, filemode, cmt, hdr)</a></td>
	<td class="summary">saves a Lua var as XML file.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#str">str (value, indent, tag)</a></td>
	<td class="summary">converts any Lua value to an XML string.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#tag">tag (var, tag)</a></td>
	<td class="summary">sets or returns tag of a LuaXML object.</td>
	</tr>
</table>
<h2><a href="#Fields">Fields</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#WS_NORMALIZE">WS_NORMALIZE</a></td>
	<td class="summary">remove &ldquo;lead in&rdquo; whitespace before tags</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#WS_PRESERVE">WS_PRESERVE</a></td>
	<td class="summary">preserve all whitespace, even between tags</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#WS_TRIM">WS_TRIM</a></td>
	<td class="summary">strip all leading / trailing whitespace</td>
	</tr>
</table>

<br/>
<br/>


    <h2><a name="Functions"></a>Functions</h2>
    <dl class="function">
    <dt>
    <a name = "append"></a>
    <strong>append (var, tag)</strong>
    </dt>
    <dd>
    appends a new subordinate LuaXML object to an existing one.
optionally sets tag


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
          the parent LuaXML object
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the tag of the appended LuaXML object
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        appended LuaXML object, or <code>nil</code> in case of errors
    </ol>




</dd>
    <dt>
    <a name = "children"></a>
    <strong>children (var, tag, key, value, maxdepth)</strong>
    </dt>
    <dd>
    iterate subelements (&ldquo;XML children&rdquo;) as <em>key &ndash; value</em> pairs.
This function is meant to be called in a generic <code>for</code> loop, similar to what
<code>ipairs(var)</code> would do. However you can easily specify additional criteria
to <a href="LuaXML.html#match">match</a>  against here, possibly reducing the overhead needed to test for
specific subelements.</p>

<p>For the resulting <code>(k, v)</code> pairs, note that <code>k</code> is just a sequential number
in the array of matched child elements, and has no direct relation to the
actual &ldquo;position&rdquo; (subtag index) within each <code>v</code>&rsquo;s parent object.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
          the table (LuaXML object) to work on
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          XML tag to be matched
        </li>
        <li><span class="parameter">key</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          attribute key to be matched
        </li>
        <li><span class="parameter">value</span>
          (optional) attribute value to be matched
        </li>
        <li><span class="parameter">maxdepth</span>
            <span class="types">optional <span class="type">number</span></span>
        maximum depth allowed, defaults to 1 (only immediate children).
You can pass 0 or <code>true</code> to iterate <em>all</em> children recursively.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

         Lua iterator function and initial state (Lua-internal use) &ndash; suitable
for a <code>for</code> loop
    </ol>


    <h3>See also:</h3>
    <ul>
         <a href="LuaXML.html#match">match</a>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example">
<span class="keyword">local</span> xml = <span class="global">require</span>(<span class="string">"LuaXML"</span>)
<span class="keyword">local</span> foobar = xml.eval(<span class="string">'&lt;foo&gt;&lt;a /&gt;&lt;b bar="no" /&gt;&lt;c bar="yes" /&gt;&lt;a /&gt;&lt;/foo&gt;'</span>)

<span class="comment">-- iterate over those children that have a "bar" attribute:
</span><span class="keyword">for</span> k, v <span class="keyword">in</span> foobar:children(<span class="keyword">nil</span>, <span class="string">"bar"</span>) <span class="keyword">do</span>
	<span class="global">print</span>(k, v:tag(), v.bar)
<span class="keyword">end</span>
<span class="comment">-- will print
</span><span class="comment">-- 1       b       no
</span><span class="comment">-- 2       c       yes
</span>
<span class="comment">-- require "bar" to be "yes":
</span><span class="keyword">for</span> k, v <span class="keyword">in</span> foobar:children(<span class="keyword">nil</span>, <span class="string">"bar"</span>, <span class="string">"yes"</span>) <span class="keyword">do</span>
	<span class="global">print</span>(k, v:tag(), v.bar)
<span class="keyword">end</span>
<span class="comment">-- will print
</span><span class="comment">-- 1       c       yes
</span>
<span class="comment">-- iterate "a" tags: (the first and fourth child will match)
</span><span class="keyword">for</span> k, v <span class="keyword">in</span> foobar:children(<span class="string">"a"</span>) <span class="keyword">do</span>
	<span class="global">print</span>(k, v:tag(), v.bar)
<span class="keyword">end</span>
<span class="comment">-- will print
</span><span class="comment">-- 1       a       nil
</span><span class="comment">-- 2       a       nil
</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "decode"></a>
    <strong>decode (str)</strong>
    </dt>
    <dd>
    converts a string from XML encoding.
This function transforms<code> str</code> by replacing any special XML encodings with
their &ldquo;plain text&rdquo; counterparts.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">str</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          string to be transformed
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

           <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        the decoded string
    </ol>


    <h3>See also:</h3>
    <ul>
         <li><a href="LuaXML.html#encode">encode</a></li>
         <li><a href="LuaXML.html#registerCode">registerCode</a></li>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example">
<span class="global">print</span>((xml.decode(<span class="string">"&amp;lt;-&amp;gt;"</span>)) <span class="comment">-- "&lt;-&gt;"
</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "encode"></a>
    <strong>encode (str)</strong>
    </dt>
    <dd>
    converts a string to XML encoding.
This function transforms<code> str</code> by replacing any special characters with
suitable XML encodings.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">str</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          string to be transformed
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

           <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        the XML-encoded string
    </ol>


    <h3>See also:</h3>
    <ul>
         <li><a href="LuaXML.html#decode">decode</a></li>
         <li><a href="LuaXML.html#registerCode">registerCode</a></li>
    </ul>

    <h3>Usage:</h3>
    <ul>
        <pre class="example">
<span class="global">print</span>(xml.encode(<span class="string">"&lt;-&gt;"</span>)) <span class="comment">-- "&amp;lt;-&amp;gt;"
</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "eval"></a>
    <strong>eval (xml, mode)</strong>
    </dt>
    <dd>
    parses an XML string into a Lua table.
The table will contain a representation of the XML tag, attributes (and their
values), and element content / subelements (either as strings or nested LuaXML
&ldquo;objects&rdquo;).</p>

<p>Note: Parsing &ldquo;wide&rdquo; strings or Unicode (UCS-2, UCS-4, UTF-16) currently is
<strong>not</strong> supported. If needed, convert such <code>xml</code> data to UTF-8 before passing it
to <code>eval()</code>. UTF-8 should be safe to use, and this function will also recognize
and ignore a UTF-8 BOM (byte order mark) at the start of <code>xml</code>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">xml</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a> or <span class="type">userdata</span></span>
        the XML to be converted. When passing a userdata type <code>xml</code> value, it must
point to a C-style (NUL-terminated) string.
        </li>
        <li><span class="parameter">mode</span>
            <span class="types">optional <span class="type">number</span></span>
        whitespace handling mode, one of the <code>WS_*</code> constants &ndash; see <a href="#Fields">Fields</a>.
defaults to <a href="LuaXML.html#WS_TRIM">WS_TRIM</a>  (compatible to previous LuaXML versions)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a LuaXML object containing the XML data, or <code>nil</code> in case of errors
    </ol>




</dd>
    <dt>
    <a name = "find"></a>
    <strong>find (var, tag, key, value)</strong>
    </dt>
    <dd>
    recursively searches a Lua table for a subelement
matching the provided tag and attribute.  See the description of <a href="LuaXML.html#match">match</a>  for
the logic involved with testing for<code> tag</code>, <code>key</code> and <code>value</code>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
          the table to be searched in
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the XML tag to be found
        </li>
        <li><span class="parameter">key</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the attribute key (= exact name) to be found
        </li>
        <li><span class="parameter">value</span>
         (optional)  the attribute value to be found
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        the first (sub-)table that satisfies the search condition,
or <code>nil</code> for no match
    </ol>




</dd>
    <dt>
    <a name = "iterate"></a>
    <strong>iterate (var, cb, tag, key, value, r, max, d)</strong>
    </dt>
    <dd>
    iterates a LuaXML object,
invoking a callback function for all matching (sub)elements. </p>

<p>The iteration starts with the variable <code>var</code> itself (= default depth 0).
A callback function <code>cb</code> gets invoked for each <a href="LuaXML.html#match">match</a> , depending on the
specified criteria. If the <code>r</code> flag is set, the process will
repeat <strong>recursively</strong> for the subelements of <code>var</code> (at depth + 1). You can
limit the scope by setting a maximum depth, or have the callback function
explicitly request to stop the iteration (by returning <code>false</code>).


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
          the table (LuaXML object) to iterate
        </li>
        <li><span class="parameter">cb</span>
            <span class="types"><span class="type">function</span></span>
        callback function. <code>callback(var, depth)</code> will be called for each matching
element.<br>
The function may return <code>false</code> to request a stop; if its result is
any other value (including <code>nil</code>), the iteration will continue.
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          XML tag to be matched
        </li>
        <li><span class="parameter">key</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          attribute key to be matched
        </li>
        <li><span class="parameter">value</span>
          (optional) attribute value to be matched
        </li>
        <li><span class="parameter">r</span>
            <span class="types">optional <span class="type">boolean</span></span>
        recursive operation. If <code>true</code>, also iterate over the subelements of <code>var</code>
        </li>
        <li><span class="parameter">max</span>
            <span class="types">optional <span class="type">number</span></span>
          maximum depth allowed
        </li>
        <li><span class="parameter">d</span>
            <span class="types">optional <span class="type">number</span></span>
          initial depth value, defaults to 0
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        The function returns two values: a counter representing the number of elements
that were successfully matched (and processed), and a boolean completion flag.
The latter is <code>true</code> for an exhaustive iteration, and <code>false</code> if was stopped
from the callback.
    </ol>


    <h3>See also:</h3>
    <ul>
         <a href="LuaXML.html#match">match</a>
    </ul>


</dd>
    <dt>
    <a name = "load"></a>
    <strong>load (filename, mode)</strong>
    </dt>
    <dd>
    loads XML data from a file and returns it as table.
Basically, this is just calling <a href="LuaXML.html#eval">eval</a>  on the given file&rsquo;s content.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">filename</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the name and path of the file to be loaded
        </li>
        <li><span class="parameter">mode</span>
            <span class="types">optional <span class="type">number</span></span>
          whitespace handling mode, defaults to <a href="LuaXML.html#WS_TRIM">WS_TRIM</a>
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a Lua table representing the XML data, or <code>nil</code> in case of errors
    </ol>




</dd>
    <dt>
    <a name = "match"></a>
    <strong>match (var, tag, key, value)</strong>
    </dt>
    <dd>
    match XML entity against given (optional) criteria.
Passing <code>nil</code> for one of the<code> tag</code>, <code>key</code>, or <code>value</code> parameters means &ldquo;don&rsquo;t
care&rdquo; (i.e. match anything for that particular aspect). So for example</p>

<pre><code>var:match(nil, "text", nil)
-- or shorter, but identical:  var:match(nil, "text")
</code></pre>

<p>will look for an XML attribute (name) &ldquo;text&rdquo; to be present in <code>var</code>, but won&rsquo;t
consider its value or the tag of <code>var</code>.</p>

<p>Note: If you want to test for a specific attribute <code>value</code>, so also have to
supply a <code>key</code> &ndash; otherwise <code>value</code> will be ignored.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
        the variable to test, normally a Lua table or LuaXML object. (If <code>var</code> is not
a table type, the test always fails.)
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        If set, has to match the XML <a href="LuaXML.html#tag">tag</a>  (i.e. must be equal to the <code>tag(var, nil)</code>
result)
        </li>
        <li><span class="parameter">key</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        If set, a corresponding <strong>attribute key</strong> needs to be present (exact name match).
        </li>
        <li><span class="parameter">value</span>
         (optional)
arbitrary Lua value. If set, the <strong>attribute value</strong> for <code>key</code> has to match it.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        either <code>nil</code> for no match; or the <code>var</code> argument properly converted to a
LuaXML object, equivalent to <code>xml.new(var)</code>.</p>

<p>This allows you to either make direct use of the matched LuaXML object, or to
use the return value in a boolean test (<code>if xml.match(&hellip;)</code>), which is a common
Lua idiom.
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example">
<span class="comment">-- each of these will either return <code>x</code>, or <code>nil</code> in case of no match
</span>
x:match(<span class="string">"foo"</span>) <span class="comment">-- test for x:tag() == "foo"
</span>x:match(<span class="keyword">nil</span>, <span class="string">"bar"</span>) <span class="comment">-- test if x has a "bar" attribute
</span>x:match(<span class="keyword">nil</span>, <span class="string">"foo"</span>, <span class="string">"bar"</span>) <span class="comment">-- test if x has a "foo" attribute that equals "bar"
</span>x:match(<span class="string">"foobar"</span>, <span class="string">"foo"</span>, <span class="string">"bar"</span>) <span class="comment">-- test for "foobar" tag, and attr "foo" == "bar"
</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "new"></a>
    <strong>new (arg, tag)</strong>
    </dt>
    <dd>
    creates a LuaXML &ldquo;object&rdquo;, and optionally sets its tag.
The function either sets the metatable of an existing Lua table, or creates a
new (empty) &ldquo;object&rdquo;. If you pass an optional<code> tag</code> string, it will be assigned
to the result.</p>

<p>(It&rsquo;s also possible to call this as <code>new(tag)</code>, which creates a new XML object
with the given tag and is equivalent to <code>new({}, tag)</code>.)</p>

<p>Note that it&rsquo;s not mandatory to use this function in order to treat a Lua table
as LuaXML object. Setting the metatable just allows the usage of a more
object-oriented syntax (e.g. <code>xmlvar:str()</code> instead of <code>xml.str(xmlvar)</code>).
XML objects created by <a href="LuaXML.html#load">load</a>  or <a href="LuaXML.html#eval">eval</a>  automatically offer the
object-oriented syntax.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">arg</span>
         (optional)  <em>(1)</em> a table to be converted to a LuaXML object,
or <em>(2)</em> the tag of the new LuaXML object
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          a tag value that will be assigned to the object
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        LuaXML object, either newly created or the conversion of <code>arg</code>;
optionally tagged as requested
    </ol>




</dd>
    <dt>
    <a name = "registerCode"></a>
    <strong>registerCode (decoded, encoded)</strong>
    </dt>
    <dd>
    registers a custom code for the conversion between non-standard characters
and XML character entities. </p>

<p>By default, only the most basic entities are known to LuaXML:</p>

<pre><code>" &lt; &gt; '
</code></pre>

<p>On top (and independent) of that, the <strong>ampersand</strong> sign always gets encoded /
decoded separately: <code>&amp;</code> &harr; <code>&amp;amp;</code>. Character codes above 127 are
directly converted to an appropriate XML encoding, representing the character
number (e.g. <code>&amp;#160;</code>). If other special encodings are needed, they can be
registered using this function.</p>

<p>Note: LuaXML now manages these encodings in a (private) standard Lua table.
This allows you to replace entries by calling <code>registerCode()</code> again, using the
same <code>decoded</code> and a different <code>encoded</code>. Encodings may even be removed later,
by explictly registering a <code>nil</code> value: <code>registerCode(decoded, nil)</code>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">decoded</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the character (sequence) to be used within Lua
        </li>
        <li><span class="parameter">encoded</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the character entity to be used in XML
        </li>
    </ul>



    <h3>See also:</h3>
    <ul>
         <li><a href="LuaXML.html#encode">encode</a></li>
         <li><a href="LuaXML.html#decode">decode</a></li>
    </ul>


</dd>
    <dt>
    <a name = "save"></a>
    <strong>save (var, filename, filemode, cmt, hdr)</strong>
    </dt>
    <dd>
    saves a Lua var as XML file.
Basically this simply exports the string representation <code>xml.str(var)</code>
(or <code>var:str()</code>), plus a standard header.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
          the variable to be saved, normally a table
        </li>
        <li><span class="parameter">filename</span>
            <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the filename to be used. An existing file of the same name gets overwritten.
        </li>
        <li><span class="parameter">filemode</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the file mode to pass to <a href="http://www.lua.org/manual/5.1/manual.html#pdf-io.open">io.open</a> , defaults to &ldquo;w&rdquo;
        </li>
        <li><span class="parameter">cmt</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <p>custom <em>comment</em> to be written at the top of the file (after the header). You
may pass an empty string if you don&rsquo;t want any comment at all, otherwise it
should preferably end with at least one newline. Defaults to:</p>

<pre><code>&lt;!-- file «filename», generated by LuaXML --&gt;\n\n
</code></pre>

        </li>
        <li><span class="parameter">hdr</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <p>custom <em>header</em>, written before anything else. You may pass an empty string if
you don&rsquo;t want any header at all, otherwise it should preferably end with a
newline. Defaults to the standard XML 1.0 declaration:</p>

<pre><code>&lt;?xml version="1.0"?&gt;\n
</code></pre>

        </li>
    </ul>




    <h3>Usage:</h3>
    <ul>
        <pre class="example">
var:save(<span class="string">"simple.xml"</span>)
var:save(<span class="string">"no-comment.xml"</span>, <span class="keyword">nil</span>, <span class="string">""</span>)
var:save(<span class="string">"custom.xml"</span>, <span class="string">"a+"</span>, <span class="string">"&lt;!-- append mode, no header --&gt;\n"</span>, <span class="string">""</span>)</pre>
    </ul>

</dd>
    <dt>
    <a name = "str"></a>
    <strong>str (value, indent, tag)</strong>
    </dt>
    <dd>
    converts any Lua value to an XML string.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">value</span>
        the value to be converted, normally a table (LuaXML object). However this
function will &lsquo;encapsulate&rsquo; other Lua values (of arbitrary type) in a way that
should make them valid XML.
<br>Note: Passing no <code>value</code> will cause the function to return <code>nil</code>.
        </li>
        <li><span class="parameter">indent</span>
            <span class="types">optional <span class="type">number</span></span>
        indentation level for &lsquo;pretty&rsquo; output. Mainly for internal use, defaults to 0.
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        the tag to be used in case <code>value</code> doesn&rsquo;t already have an &lsquo;implicit&rsquo; tag.
Mainly for internal use.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

           <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        an XML string, or <code>nil</code> in case of errors.
    </ol>




</dd>
    <dt>
    <a name = "tag"></a>
    <strong>tag (var, tag)</strong>
    </dt>
    <dd>
    sets or returns tag of a LuaXML object.
This method is just &ldquo;syntactic sugar&rdquo; (using a typical Lua term) that allows
the writing of clearer code. LuaXML stores the tag value of an XML statement
at table index 0, hence it can be simply accessed or altered by <code>var[0]</code>.
However, writing <code>var:tag()</code> for access or <code>var:tag(&ldquo;newTag&rdquo;)</code> for altering
may be more self explanatory (and future-proof in case LuaXML&rsquo;s tag handling
should ever change).


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">var</span>
          the variable whose tag should be accessed, a LuaXML object
        </li>
        <li><span class="parameter">tag</span>
            <span class="types">optional <a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
          the new tag to be set
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

          If you have passed a new tag, the function will return <code>var</code> (with
its tag changed); otherwise the result will be the current tag of <code>var</code>
(normally a string).
    </ol>




</dd>
</dl>
    <h2><a name="Fields"></a>Fields</h2>
    <dl class="function">
    <dt>
    <a name = "WS_NORMALIZE"></a>
    <strong>WS_NORMALIZE</strong>
    </dt>
    <dd>
    remove &ldquo;lead in&rdquo; whitespace before tags


    <ul>
        <li><span class="parameter">WS_NORMALIZE</span>


        </li>
    </ul>





</dd>
    <dt>
    <a name = "WS_PRESERVE"></a>
    <strong>WS_PRESERVE</strong>
    </dt>
    <dd>
    preserve all whitespace, even between tags


    <ul>
        <li><span class="parameter">WS_PRESERVE</span>


        </li>
    </ul>





</dd>
    <dt>
    <a name = "WS_TRIM"></a>
    <strong>WS_TRIM</strong>
    </dt>
    <dd>
    strip all leading / trailing whitespace


    <ul>
        <li><span class="parameter">WS_TRIM</span>


        </li>
    </ul>





</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.2</a></i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
